在這次鐵人賽看 VueUse API 原始碼的時候，覺得官方文件看起來滿舒服，發現是用 VitePress 這套工具生成的。

我有先簡單跟著 VitePress 官方文件做一個範例，部署在 GitHub Page 上，
最後會用這個已經建好的 VitePress 範例，把這次鐵人賽實作的 API（部分）搬進 VitePress，目標是復刻跟 VueUse 效果差不多的文件頁面。

今天先來看一些文件共用的區塊，會看到一些 VitePress 基本用法。

Deploy 一個基本 VitePress 部落格

這部分就不細談，當初是照著官方文件，從 getting-started 到 deploy 的步驟做一次，中途除了兩個部署 error，其他滿順利就建好了。

關於其中一個部署問題，如果是用 pnpm 的話，官方文件 有提到要解除註解 pnpm 的部分：

# - uses: pnpm/action-setup@v3 # Uncomment this if you're using pnpm

這段解除註解後部屬我有遇到 error，訊息說要指定 pnpm 版本，後來改成以下寫法就部署成功了

- uses: pnpm/action-setup@v3 # Uncomment this if you're using pnpm
    with:
      version: 8

版本的話可以依照自己使用的 pnpm 版本作修改。

另一個問題是，如果 .vitepress 目錄不是放在根目錄，需要修改 sh：

- name: Upload artifact
    uses: actions/upload-pages-artifact@v3
    with:
      path: projects/.vitepress/dist # <- 本來是 .vitepress/dist

我是把 .vitepress 目錄放在 projects 目錄中，所以這邊改成 projects/.vitepress/dist。

VueUse 文件首頁

VueUse 官方文件：https://vueuse.org/

決定這頁內容的 Markdown 檔案位置：https://github.com/vueuse/vueuse/blob/main/packages/index.md?plain=1

根據 VitePress 文件說明，預設會把 .vitepress 放在專案根目錄，從這個根目錄找到的 index.md 就會被當成首頁內容。如果要像 VueUse 把 .vitepress 放在 pacakges folder 中，可以把指令改成：

• dev：vitepress dev packages
• build：vitepress build packages

這樣就會抓 packages 目錄中的 index.md 來當首頁。index.md 裡面的語法可以大概參照一下首頁畫面，會比較知道彼此的關係。

VueUse Nav 設定

決定固定在 VueUse 文件上方的 Navigation 內容的 Markdown 檔案位置：https://github.com/vueuse/vueuse/blob/main/packages/.vitepress/config.ts

可以看到這段設定就是寫在 VitePress 設定檔中。在檔案中找到這個片段：

themeConfig: {
    logo: '/favicon.svg',
    algolia: {
      appId: 'NBQWY48OOR',
      apiKey: 'c5fd82eb1100c2110c1690e0756d8ba5',
      indexName: 'vueuse',
    },
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vueuse/vueuse' },
      { icon: 'discord', link: 'https://chat.antfu.me' },
      { icon: 'twitter', link: 'https://twitter.com/vueuse' },
    ],
    nav: [
      {
        text: 'Guide',
        items: [
          { text: 'Guide', items: Guide },
          { text: 'Learn', items: Learn },
          { text: 'Links', items: Links },
        ],
      },
      {
        text: 'Functions',
        items: [
          {
            text: '',
            items: [
              { text: 'All Functions', link: '/functions#' },
              { text: 'Recent Updated', link: '/functions#sort=updated' },
            ],
          },
          { text: 'Core', items: CoreCategories },
          { text: 'Add-ons', items: AddonCategories },
        ],
      },
      {
        text: 'Add-ons',
        link: '/add-ons',
      },
      {
        text: 'Playground',
        link: 'https://play.vueuse.org',
      },
      {
        text: currentVersion,
        items: [
          {
            items: [
              { text: 'Release Notes', link: 'https://github.com/vueuse/vueuse/releases' },
            ],
          },
          {
            text: 'Versions',
            items: versions.map(i => i.version === currentVersion
              ? {
                  text: `${i.version} (Current)`,
                  activeMatch: '/', // always active
                  link: '/',
                }
              : {
                  text: i.version,
                  link: i.link!,
                }),
          },
        ],

      },
    ],
},

畫面上方 Nav 從左到右看：

• logo：對就那個 logo XD。
• algolia：搜尋模組，VitePress 本身也有內建的搜尋功能，不過 VueUse 這邊是用 algolia 這個工具，VitePress 文件也有提到，相關設定可以參考：https://vitepress.dev/reference/default-theme-search ，之後實作我會先用 VitePress 內建的搜尋，因為 algolia 還需要申請，看起來比較麻煩。
• nav：導覽列表以及對應下拉選單就是在這邊設定的。
• socialLinks：最右邊的社群連結。

VueUse Functions 頁面

VueUse 官方文件：https://vueuse.org/functions.html

決定這頁內容的 Markdown 檔案位置：https://github.com/vueuse/vueuse/blob/main/packages/functions.md?plain=1

裡面內容就只有這樣：

# Functions

<FunctionsList />

所以那個頁面的內容就是 FunctionsList 這個組件，這也是 VitePress 的特色之一，可以在 Markdown 中引用 Vue 組件。

這類只會給 VitePress 文件做使用的組件，看起來是會寫在 .vitepress/theme/components 目錄中。
VueUse 目錄位置：https://github.com/vueuse/vueuse/tree/main/packages/.vitepress/theme/components

今天就先看到 VueUse Functions 頁面，明天會開始看 VueUse API 頁面的文件是怎麼透過 VitePress 生成的。